

<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
  <meta charset="utf-8" />
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  
  <title>PubSub 同步模块 &mdash; Ceph Documentation</title>
  

  
  <link rel="stylesheet" href="../../_static/ceph.css" type="text/css" />
  <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
  <link rel="stylesheet" href="../../_static/graphviz.css" type="text/css" />
  <link rel="stylesheet" href="../../_static/css/custom.css" type="text/css" />

  
  
    <link rel="shortcut icon" href="../../_static/favicon.ico"/>
  

  
  

  

  
  <!--[if lt IE 9]>
    <script src="../../_static/js/html5shiv.min.js"></script>
  <![endif]-->
  
    
      <script type="text/javascript" id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></script>
        <script src="../../_static/jquery.js"></script>
        <script src="../../_static/underscore.js"></script>
        <script src="../../_static/doctools.js"></script>
    
    <script type="text/javascript" src="../../_static/js/theme.js"></script>

    
    <link rel="index" title="Index" href="../../genindex/" />
    <link rel="search" title="Search" href="../../search/" />
    <link rel="next" title="S3 桶通知的兼容性" href="../s3-notification-compatibility/" />
    <link rel="prev" title="云同步模块" href="../cloud-sync-module/" /> 
</head>

<body class="wy-body-for-nav">

   
  <header class="top-bar">
    

















<div role="navigation" aria-label="breadcrumbs navigation">

  <ul class="wy-breadcrumbs">
    
      <li><a href="../../" class="icon icon-home"></a> &raquo;</li>
        
          <li><a href="../">Ceph 对象网关</a> &raquo;</li>
        
          <li><a href="../sync-modules/">同步模块</a> &raquo;</li>
        
      <li>PubSub 同步模块</li>
    
    
      <li class="wy-breadcrumbs-aside">
        
          
            <a href="../../_sources/radosgw/pubsub-module.rst.txt" rel="nofollow"> View page source</a>
          
        
      </li>
    
  </ul>

  
  <hr/>
</div>
  </header>
  <div class="wy-grid-for-nav">
    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search"  style="background: #eee" >
          

          
            <a href="../../">
          

          
            
            <img src="../../_static/logo.png" class="logo" alt="Logo"/>
          
          </a>

          

          
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../../search/" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>

          
        </div>

        
        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
            
            
              
            
            
              <ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../start/intro/">Ceph 简介</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../install/">安装 Ceph</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../cephadm/">Cephadm</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../rados/">Ceph 存储集群</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../cephfs/">Ceph 文件系统</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../rbd/">Ceph 块设备</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../">Ceph 对象网关</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../frontends/">HTTP 前端</a></li>
<li class="toctree-l2"><a class="reference internal" href="../placement/">存储池归置与存储类</a></li>
<li class="toctree-l2"><a class="reference internal" href="../multisite/">多站配置</a></li>
<li class="toctree-l2"><a class="reference internal" href="../multisite-sync-policy/">多站同步策略配置</a></li>
<li class="toctree-l2"><a class="reference internal" href="../pools/">存储池的配置</a></li>
<li class="toctree-l2"><a class="reference internal" href="../config-ref/">配置参考</a></li>
<li class="toctree-l2"><a class="reference internal" href="../admin/">管理指南</a></li>
<li class="toctree-l2"><a class="reference internal" href="../s3/">S3 API</a></li>
<li class="toctree-l2"><a class="reference internal" href="../rgw-cache/">Data caching and CDN</a></li>
<li class="toctree-l2"><a class="reference internal" href="../swift/">Swift API</a></li>
<li class="toctree-l2"><a class="reference internal" href="../adminops/">管理操作 API</a></li>
<li class="toctree-l2"><a class="reference internal" href="../api/">Python 接口</a></li>
<li class="toctree-l2"><a class="reference internal" href="../nfs/">通过 NFS 导出</a></li>
<li class="toctree-l2"><a class="reference internal" href="../keystone/">与 OpenStack Keystone 对接</a></li>
<li class="toctree-l2"><a class="reference internal" href="../barbican/">与 OpenStack Barbican 对接</a></li>
<li class="toctree-l2"><a class="reference internal" href="../vault/">与 HashiCorp Vault 对接</a></li>
<li class="toctree-l2"><a class="reference internal" href="../kmip/">KMIP Integration</a></li>
<li class="toctree-l2"><a class="reference internal" href="../opa/">与 Open Policy Agent 对接</a></li>
<li class="toctree-l2"><a class="reference internal" href="../multitenancy/">多租户</a></li>
<li class="toctree-l2"><a class="reference internal" href="../compression/">压缩</a></li>
<li class="toctree-l2"><a class="reference internal" href="../ldap-auth/">LDAP 认证</a></li>
<li class="toctree-l2"><a class="reference internal" href="../encryption/">服务器端加密</a></li>
<li class="toctree-l2"><a class="reference internal" href="../bucketpolicy/">桶策略</a></li>
<li class="toctree-l2"><a class="reference internal" href="../dynamicresharding/">动态的桶索引重分片</a></li>
<li class="toctree-l2"><a class="reference internal" href="../mfa/">多因子认证</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../sync-modules/">同步模块</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="../elastic-sync-module/">ElasticSearch 同步模块</a></li>
<li class="toctree-l3"><a class="reference internal" href="../cloud-sync-module/">Cloud 同步模块</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#">PubSub 模块</a><ul>
<li class="toctree-l4"><a class="reference internal" href="../s3-notification-compatibility/">S3 Bucket Notification Compatibility</a></li>
<li class="toctree-l4"><a class="reference internal" href="#pubsub-zone-configuration">PubSub Zone Configuration</a></li>
<li class="toctree-l4"><a class="reference internal" href="#topic-and-subscription-management-via-cli">Topic and Subscription Management via CLI</a></li>
<li class="toctree-l4"><a class="reference internal" href="#pubsub-performance-stats">PubSub Performance Stats</a></li>
<li class="toctree-l4"><a class="reference internal" href="#pubsub-rest-api">PubSub REST API</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="../archive-sync-module/">Archive 同步模块</a></li>
<li class="toctree-l3"><a class="reference internal" href="../sync-modules/#id2">需求和假设</a></li>
<li class="toctree-l3"><a class="reference internal" href="../sync-modules/#id3">同步模块的配置</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../notifications/">Bucket Notifications</a></li>
<li class="toctree-l2"><a class="reference internal" href="../layout/">RADOS 中的数据布局</a></li>
<li class="toctree-l2"><a class="reference internal" href="../STS/">STS</a></li>
<li class="toctree-l2"><a class="reference internal" href="../STSLite/">STS Lite</a></li>
<li class="toctree-l2"><a class="reference internal" href="../keycloak/">Keycloak</a></li>
<li class="toctree-l2"><a class="reference internal" href="../role/">Role</a></li>
<li class="toctree-l2"><a class="reference internal" href="../session-tags/">Session Tags</a></li>
<li class="toctree-l2"><a class="reference internal" href="../orphans/">Orphan List and Associated Tooliing</a></li>
<li class="toctree-l2"><a class="reference internal" href="../oidc/">OpenID Connect Provider</a></li>
<li class="toctree-l2"><a class="reference internal" href="../troubleshooting/">故障排除</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../man/8/radosgw/">radosgw 手册页</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../man/8/radosgw-admin/">radosgw-admin 手册页</a></li>
<li class="toctree-l2"><a class="reference internal" href="../qat-accel/">使用 QAT 为加密和压缩提速</a></li>
<li class="toctree-l2"><a class="reference internal" href="../s3select/">S3-select</a></li>
<li class="toctree-l2"><a class="reference internal" href="../lua-scripting/">Lua Scripting</a></li>
<li class="toctree-l2"><a class="reference internal" href="../d3n_datacache/">D3N Data Cache</a></li>
<li class="toctree-l2"><a class="reference internal" href="../cloud-transition/">Cloud Transition</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../mgr/">Ceph 管理器守护进程</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../mgr/dashboard/">Ceph 仪表盘</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../api/">API 文档</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../architecture/">体系结构</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../dev/developer_guide/">开发者指南</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../dev/internals/">Ceph 内幕</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../governance/">项目管理</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../foundation/">Ceph 基金会</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../ceph-volume/">ceph-volume</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../releases/general/">Ceph 版本（总目录）</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../releases/">Ceph 版本（索引）</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../security/">Security</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../glossary/">Ceph 术语</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../jaegertracing/">Tracing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../translation_cn/">中文版翻译资源</a></li>
</ul>

            
          
        </div>
        
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" aria-label="top navigation">
        
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../../">Ceph</a>
        
      </nav>


      <div class="wy-nav-content">
        
        <div class="rst-content">
        
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
<div id="dev-warning" class="admonition note">
  <p class="first admonition-title">Notice</p>
  <p class="last">This document is for a development version of Ceph.</p>
</div>
  <div id="docubetter" align="right" style="padding: 5px; font-weight: bold;">
    <a href="https://pad.ceph.com/p/Report_Documentation_Bugs">Report a Documentation Bug</a>
  </div>

  
  <div class="section" id="pubsub">
<h1><a class="toc-backref" href="#id1">PubSub 同步模块</a><a class="headerlink" href="#pubsub" title="Permalink to this headline">¶</a></h1>
<div class="versionadded">
<p><span class="versionmodified added">New in version Nautilus.</span></p>
</div>
<div class="contents topic" id="contents">
<p class="topic-title">Contents</p>
<ul class="simple">
<li><p><a class="reference internal" href="#pubsub" id="id1">PubSub 同步模块</a></p>
<ul>
<li><p><a class="reference internal" href="#pubsub-zone-configuration" id="id2">PubSub Zone Configuration</a></p>
<ul>
<li><p><a class="reference internal" href="#pubsub-zone-configuration-parameters" id="id3">PubSub Zone Configuration Parameters</a></p></li>
<li><p><a class="reference internal" href="#configuring-parameters-via-cli" id="id4">Configuring Parameters via CLI</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#topic-and-subscription-management-via-cli" id="id5">Topic and Subscription Management via CLI</a></p></li>
<li><p><a class="reference internal" href="#pubsub-performance-stats" id="id6">PubSub Performance Stats</a></p></li>
<li><p><a class="reference internal" href="#pubsub-rest-api" id="id7">PubSub REST API</a></p>
<ul>
<li><p><a class="reference internal" href="#topics" id="id8">Topics</a></p>
<ul>
<li><p><a class="reference internal" href="#create-a-topic" id="id9">Create a Topic</a></p></li>
<li><p><a class="reference internal" href="#get-topic-information" id="id10">Get Topic Information</a></p></li>
<li><p><a class="reference internal" href="#delete-topic" id="id11">Delete Topic</a></p></li>
<li><p><a class="reference internal" href="#list-topics" id="id12">List Topics</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#s3-compliant-notifications" id="id13">S3-Compliant Notifications</a></p></li>
<li><p><a class="reference internal" href="#non-s3-compliant-notifications" id="id14">Non S3-Compliant Notifications</a></p>
<ul>
<li><p><a class="reference internal" href="#create-a-notification" id="id15">Create a Notification</a></p></li>
<li><p><a class="reference internal" href="#delete-notification-information" id="id16">Delete Notification Information</a></p></li>
<li><p><a class="reference internal" href="#list-notifications" id="id17">List Notifications</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#subscriptions" id="id18">Subscriptions</a></p>
<ul>
<li><p><a class="reference internal" href="#create-a-subscription" id="id19">Create a Subscription</a></p></li>
<li><p><a class="reference internal" href="#get-subscription-information" id="id20">Get Subscription Information</a></p></li>
<li><p><a class="reference internal" href="#delete-subscription" id="id21">Delete Subscription</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#events" id="id22">Events</a></p>
<ul>
<li><p><a class="reference internal" href="#pull-events" id="id23">Pull Events</a></p></li>
<li><p><a class="reference internal" href="#ack-event" id="id24">Ack Event</a></p></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<p>This sync module provides a publish and subscribe mechanism for the object store modification
events. Events are published into predefined topics. Topics can be subscribed to, and events
can be pulled from them. Events need to be acked. Also, events will expire and disappear
after a period of time.</p>
<p>A push notification mechanism exists too, currently supporting HTTP,
AMQP0.9.1 and Kafka endpoints. In this case, the events are pushed to an endpoint on top of storing them in Ceph. If events should only be pushed to an endpoint
and do not need to be stored in Ceph, the <a class="reference external" href="../notifications">Bucket Notification</a> mechanism should be used instead of pubsub sync module.</p>
<p>A user can create different topics. A topic entity is defined by its name and is per tenant. A
user can only associate its topics (via notification configuration) with buckets it owns.</p>
<p>In order to publish events for specific bucket a notification entity needs to be created. A
notification can be created on a subset of event types, or for all event types (default).
There can be multiple notifications for any specific topic, and the same topic could be used for multiple notifications.</p>
<p>A subscription to a topic can also be defined. There can be multiple subscriptions for any
specific topic.</p>
<p>REST API has been defined to provide configuration and control interfaces for the pubsub
mechanisms. This API has two flavors, one is S3-compatible and one is not. The two flavors can be used
together, although it is recommended to use the S3-compatible one.
The S3-compatible API is similar to the one used in the bucket notification mechanism.</p>
<p>Events are stored as RGW objects in a special bucket, under a special user (pubsub control user). Events cannot
be accessed directly, but need to be pulled and acked using the new REST API.</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../s3-notification-compatibility/">S3 Bucket Notification Compatibility</a></li>
</ul>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>To enable bucket notifications API, the <cite>rgw_enable_apis</cite> configuration parameter should contain: “notifications”.</p>
</div>
<div class="section" id="pubsub-zone-configuration">
<h2><a class="toc-backref" href="#id2">PubSub Zone Configuration</a><a class="headerlink" href="#pubsub-zone-configuration" title="Permalink to this headline">¶</a></h2>
<p>The pubsub sync module requires the creation of a new zone in a <a class="reference internal" href="../multisite/#multisite"><span class="std std-ref">多站</span></a> environment…
First, a master zone must exist (see: <a class="reference internal" href="../multisite/#master-zone-label"><span class="std std-ref">配置主域</span></a>),
then a secondary zone should be created (see <a class="reference internal" href="../multisite/#secondary-zone-label"><span class="std std-ref">配置副域</span></a>).
In the creation of the secondary zone, its tier type must be set to <code class="docutils literal notranslate"><span class="pre">pubsub</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># radosgw-admin zone create --rgw-zonegroup={zone-group-name} \</span>
                            <span class="o">--</span><span class="n">rgw</span><span class="o">-</span><span class="n">zone</span><span class="o">=</span><span class="p">{</span><span class="n">zone</span><span class="o">-</span><span class="n">name</span><span class="p">}</span> \
                            <span class="o">--</span><span class="n">endpoints</span><span class="o">=</span><span class="p">{</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">fqdn</span><span class="p">}[,{</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">fqdn</span><span class="p">}]</span> \
                            <span class="o">--</span><span class="n">sync</span><span class="o">-</span><span class="n">from</span><span class="o">-</span><span class="nb">all</span><span class="o">=</span><span class="mi">0</span> \
                            <span class="o">--</span><span class="n">sync</span><span class="o">-</span><span class="n">from</span><span class="o">=</span><span class="p">{</span><span class="n">master</span><span class="o">-</span><span class="n">zone</span><span class="o">-</span><span class="n">name</span><span class="p">}</span> \
                            <span class="o">--</span><span class="n">tier</span><span class="o">-</span><span class="nb">type</span><span class="o">=</span><span class="n">pubsub</span>
</pre></div>
</div>
<div class="section" id="pubsub-zone-configuration-parameters">
<h3><a class="toc-backref" href="#id3">PubSub Zone Configuration Parameters</a><a class="headerlink" href="#pubsub-zone-configuration-parameters" title="Permalink to this headline">¶</a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
    <span class="s2">&quot;tenant&quot;</span><span class="p">:</span> <span class="o">&lt;</span><span class="n">tenant</span><span class="o">&gt;</span><span class="p">,</span>             <span class="c1"># default: &lt;empty&gt;</span>
    <span class="s2">&quot;uid&quot;</span><span class="p">:</span> <span class="o">&lt;</span><span class="n">uid</span><span class="o">&gt;</span><span class="p">,</span>                   <span class="c1"># default: &quot;pubsub&quot;</span>
    <span class="s2">&quot;data_bucket_prefix&quot;</span><span class="p">:</span> <span class="o">&lt;</span><span class="n">prefix</span><span class="o">&gt;</span>  <span class="c1"># default: &quot;pubsub-&quot;</span>
    <span class="s2">&quot;data_oid_prefix&quot;</span><span class="p">:</span> <span class="o">&lt;</span><span class="n">prefix</span><span class="o">&gt;</span>     <span class="c1">#</span>
    <span class="s2">&quot;events_retention_days&quot;</span><span class="p">:</span> <span class="o">&lt;</span><span class="n">days</span><span class="o">&gt;</span> <span class="c1"># default: 7</span>
<span class="p">}</span>
</pre></div>
</div>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">tenant</span></code> (string)</p></li>
</ul>
<p>The tenant of the pubsub control user.</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">uid</span></code> (string)</p></li>
</ul>
<p>The uid of the pubsub control user.</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">data_bucket_prefix</span></code> (string)</p></li>
</ul>
<p>The prefix of the bucket name that will be created to store events for specific topic.</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">data_oid_prefix</span></code> (string)</p></li>
</ul>
<p>The oid prefix for the stored events.</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">events_retention_days</span></code> (integer)</p></li>
</ul>
<p>How many days to keep events that weren’t acked.</p>
</div>
<div class="section" id="configuring-parameters-via-cli">
<h3><a class="toc-backref" href="#id4">Configuring Parameters via CLI</a><a class="headerlink" href="#configuring-parameters-via-cli" title="Permalink to this headline">¶</a></h3>
<p>The tier configuration could be set using the following command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># radosgw-admin zone modify --rgw-zonegroup={zone-group-name} \</span>
                             <span class="o">--</span><span class="n">rgw</span><span class="o">-</span><span class="n">zone</span><span class="o">=</span><span class="p">{</span><span class="n">zone</span><span class="o">-</span><span class="n">name</span><span class="p">}</span> \
                             <span class="o">--</span><span class="n">tier</span><span class="o">-</span><span class="n">config</span><span class="o">=</span><span class="p">{</span><span class="n">key</span><span class="p">}</span><span class="o">=</span><span class="p">{</span><span class="n">val</span><span class="p">}[,{</span><span class="n">key</span><span class="p">}</span><span class="o">=</span><span class="p">{</span><span class="n">val</span><span class="p">}]</span>
</pre></div>
</div>
<p>Where the <code class="docutils literal notranslate"><span class="pre">key</span></code> in the configuration specifies the configuration variable that needs to be updated (from the list above), and
the <code class="docutils literal notranslate"><span class="pre">val</span></code> specifies its new value. For example, setting the pubsub control user <code class="docutils literal notranslate"><span class="pre">uid</span></code> to <code class="docutils literal notranslate"><span class="pre">user_ps</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># radosgw-admin zone modify --rgw-zonegroup={zone-group-name} \</span>
                             <span class="o">--</span><span class="n">rgw</span><span class="o">-</span><span class="n">zone</span><span class="o">=</span><span class="p">{</span><span class="n">zone</span><span class="o">-</span><span class="n">name</span><span class="p">}</span> \
                             <span class="o">--</span><span class="n">tier</span><span class="o">-</span><span class="n">config</span><span class="o">=</span><span class="n">uid</span><span class="o">=</span><span class="n">pubsub</span>
</pre></div>
</div>
<p>A configuration field can be removed by using <code class="docutils literal notranslate"><span class="pre">--tier-config-rm={key}</span></code>.</p>
</div>
</div>
<div class="section" id="topic-and-subscription-management-via-cli">
<h2><a class="toc-backref" href="#id5">Topic and Subscription Management via CLI</a><a class="headerlink" href="#topic-and-subscription-management-via-cli" title="Permalink to this headline">¶</a></h2>
<p>Configuration of all topics, associated with a tenant, could be fetched using the following command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># radosgw-admin topic list [--tenant={tenant}]</span>
</pre></div>
</div>
<p>Configuration of a specific topic could be fetched using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># radosgw-admin topic get --topic={topic-name} [--tenant={tenant}]</span>
</pre></div>
</div>
<p>And removed using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># radosgw-admin topic rm --topic={topic-name} [--tenant={tenant}]</span>
</pre></div>
</div>
<p>Configuration of a subscription could be fetched using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># radosgw-admin subscription get --subscription={topic-name} [--tenant={tenant}]</span>
</pre></div>
</div>
<p>And removed using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># radosgw-admin subscription rm --subscription={topic-name} [--tenant={tenant}]</span>
</pre></div>
</div>
<p>To fetch all of the events stored in a subcription, use:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># radosgw-admin subscription pull --subscription={topic-name} [--marker={last-marker}] [--tenant={tenant}]</span>
</pre></div>
</div>
<p>To ack (and remove) an event from a subscription, use:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># radosgw-admin subscription ack --subscription={topic-name} --event-id={event-id} [--tenant={tenant}]</span>
</pre></div>
</div>
</div>
<div class="section" id="pubsub-performance-stats">
<h2><a class="toc-backref" href="#id6">PubSub Performance Stats</a><a class="headerlink" href="#pubsub-performance-stats" title="Permalink to this headline">¶</a></h2>
<p>Same counters are shared between the pubsub sync module and the notification mechanism.</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">pubsub_event_triggered</span></code>: running counter of events with at lease one topic associated with them</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">pubsub_event_lost</span></code>: running counter of events that had topics and subscriptions associated with them but that were not stored or pushed to any of the subscriptions</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">pubsub_store_ok</span></code>: running counter, for all subscriptions, of stored events</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">pubsub_store_fail</span></code>: running counter, for all subscriptions, of events failed to be stored</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">pubsub_push_ok</span></code>: running counter, for all subscriptions, of events successfully pushed to their endpoint</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">pubsub_push_fail</span></code>: running counter, for all subscriptions, of events failed to be pushed to their endpoint</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">pubsub_push_pending</span></code>: gauge value of events pushed to an endpoint but not acked or nacked yet</p></li>
</ul>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p><code class="docutils literal notranslate"><span class="pre">pubsub_event_triggered</span></code> and <code class="docutils literal notranslate"><span class="pre">pubsub_event_lost</span></code> are incremented per event, while:
<code class="docutils literal notranslate"><span class="pre">pubsub_store_ok</span></code>, <code class="docutils literal notranslate"><span class="pre">pubsub_store_fail</span></code>, <code class="docutils literal notranslate"><span class="pre">pubsub_push_ok</span></code>, <code class="docutils literal notranslate"><span class="pre">pubsub_push_fail</span></code>, are incremented per store/push action on each subscriptions.</p>
</div>
</div>
<div class="section" id="pubsub-rest-api">
<h2><a class="toc-backref" href="#id7">PubSub REST API</a><a class="headerlink" href="#pubsub-rest-api" title="Permalink to this headline">¶</a></h2>
<div class="admonition tip">
<p class="admonition-title">Tip</p>
<p>PubSub REST calls, and only them, should be sent to an RGW which belong to a PubSub zone</p>
</div>
<div class="section" id="topics">
<h3><a class="toc-backref" href="#id8">Topics</a><a class="headerlink" href="#topics" title="Permalink to this headline">¶</a></h3>
<div class="section" id="create-a-topic">
<span id="radosgw-create-a-topic"></span><h4><a class="toc-backref" href="#id9">Create a Topic</a><a class="headerlink" href="#create-a-topic" title="Permalink to this headline">¶</a></h4>
<p>This will create a new topic. Topic creation is needed both for both flavors of the API.
Optionally the topic could be provided with push endpoint parameters that would be used later
when an S3-compatible notification is created.
Upon successful request, the response will include the topic ARN that could be later used to reference this topic in an S3-compatible notification request.
To update a topic, use the same command used for topic creation, with the topic name of an existing topic and different endpoint values.</p>
<div class="admonition tip">
<p class="admonition-title">Tip</p>
<p>Any S3-compatible notification already associated with the topic needs to be re-created for the topic update to take effect</p>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>PUT /topics/&lt;topic-name&gt;[?OpaqueData=&lt;opaque data&gt;][&amp;push-endpoint=&lt;endpoint&gt;[&amp;amqp-exchange=&lt;exchange&gt;][&amp;amqp-ack-level=none|broker|routable][&amp;verify-ssl=true|false][&amp;kafka-ack-level=none|broker][&amp;use-ssl=true|false][&amp;ca-location=&lt;file path&gt;]]
</pre></div>
</div>
<p>Request parameters:</p>
<ul class="simple">
<li><p>push-endpoint: URI of an endpoint to send push notification to</p></li>
<li><p>OpaqueData: opaque data is set in the topic configuration and added to all notifications triggered by the topic</p></li>
</ul>
<p>The endpoint URI may include parameters depending with the type of endpoint:</p>
<ul class="simple">
<li><p>HTTP endpoint</p></li>
</ul>
<blockquote>
<div><ul class="simple">
<li><p>URI: <code class="docutils literal notranslate"><span class="pre">http[s]://&lt;fqdn&gt;[:&lt;port]</span></code></p></li>
<li><p>port defaults to: 80/443 for HTTP/S accordingly</p></li>
<li><p>verify-ssl: indicate whether the server certificate is validated by the client or not (“true” by default)</p></li>
</ul>
</div></blockquote>
<ul class="simple">
<li><p>AMQP0.9.1 endpoint</p></li>
</ul>
<blockquote>
<div><ul class="simple">
<li><p>URI: <code class="docutils literal notranslate"><span class="pre">amqp[s]://[&lt;user&gt;:&lt;password&gt;&#64;]&lt;fqdn&gt;[:&lt;port&gt;][/&lt;vhost&gt;]</span></code></p></li>
<li><p>user/password defaults to: guest/guest</p></li>
<li><p>user/password may only be provided over HTTPS. Topic creation request will be rejected if not</p></li>
<li><p>port defaults to: 5672/5671 for unencrypted/SSL-encrypted connections</p></li>
<li><p>vhost defaults to: “/”</p></li>
<li><p>verify-ssl: indicate whether the server certificate is validated by the client or not (“true” by default)</p></li>
<li><p>if <code class="docutils literal notranslate"><span class="pre">ca-location</span></code> is provided, and secure connection is used, the specified CA will be used, instead of the default one, to authenticate the broker</p></li>
<li><p>amqp-exchange: the exchanges must exist and be able to route messages based on topics (mandatory parameter for AMQP0.9.1). Different topics pointing to the same endpoint must use the same exchange</p></li>
<li><p>amqp-ack-level: no end2end acking is required, as messages may persist in the broker before delivered into their final destination. Three ack methods exist:</p></li>
</ul>
<blockquote>
<div><ul class="simple">
<li><p>“none”: message is considered “delivered” if sent to broker</p></li>
<li><p>“broker”: message is considered “delivered” if acked by broker (default)</p></li>
<li><p>“routable”: message is considered “delivered” if broker can route to a consumer</p></li>
</ul>
</div></blockquote>
</div></blockquote>
<div class="admonition tip">
<p class="admonition-title">Tip</p>
<p>The topic-name (see <a class="reference internal" href="#radosgw-create-a-topic"><span class="std std-ref">Create a Topic</span></a>) is used for the AMQP topic (“routing key” for a topic exchange)</p>
</div>
<ul class="simple">
<li><p>Kafka endpoint</p></li>
</ul>
<blockquote>
<div><ul class="simple">
<li><p>URI: <code class="docutils literal notranslate"><span class="pre">kafka://[&lt;user&gt;:&lt;password&gt;&#64;]&lt;fqdn&gt;[:&lt;port]</span></code></p></li>
<li><p>if <code class="docutils literal notranslate"><span class="pre">use-ssl</span></code> is set to “true”, secure connection will be used for connecting with the broker (“false” by default)</p></li>
<li><p>if <code class="docutils literal notranslate"><span class="pre">ca-location</span></code> is provided, and secure connection is used, the specified CA will be used, instead of the default one, to authenticate the broker</p></li>
<li><p>user/password may only be provided over HTTPS. Topic creation request will be rejected if not</p></li>
<li><p>user/password may only be provided together with <code class="docutils literal notranslate"><span class="pre">use-ssl</span></code>, connection to the broker would fail if not</p></li>
<li><p>port defaults to: 9092</p></li>
<li><p>kafka-ack-level: no end2end acking is required, as messages may persist in the broker before delivered into their final destination. Two ack methods exist:</p></li>
</ul>
<blockquote>
<div><ul class="simple">
<li><p>“none”: message is considered “delivered” if sent to broker</p></li>
<li><p>“broker”: message is considered “delivered” if acked by broker (default)</p></li>
</ul>
</div></blockquote>
</div></blockquote>
<p>The topic ARN in the response will have the following format:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">arn</span><span class="p">:</span><span class="n">aws</span><span class="p">:</span><span class="n">sns</span><span class="p">:</span><span class="o">&lt;</span><span class="n">zone</span><span class="o">-</span><span class="n">group</span><span class="o">&gt;</span><span class="p">:</span><span class="o">&lt;</span><span class="n">tenant</span><span class="o">&gt;</span><span class="p">:</span><span class="o">&lt;</span><span class="n">topic</span><span class="o">&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="get-topic-information">
<h4><a class="toc-backref" href="#id10">Get Topic Information</a><a class="headerlink" href="#get-topic-information" title="Permalink to this headline">¶</a></h4>
<p>Returns information about specific topic. This includes subscriptions to that topic, and push-endpoint information, if provided.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">GET</span> <span class="o">/</span><span class="n">topics</span><span class="o">/&lt;</span><span class="n">topic</span><span class="o">-</span><span class="n">name</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>Response will have the following format (JSON):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
    <span class="s2">&quot;topic&quot;</span><span class="p">:{</span>
        <span class="s2">&quot;user&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
        <span class="s2">&quot;name&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
        <span class="s2">&quot;dest&quot;</span><span class="p">:{</span>
            <span class="s2">&quot;bucket_name&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
            <span class="s2">&quot;oid_prefix&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
            <span class="s2">&quot;push_endpoint&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
            <span class="s2">&quot;push_endpoint_args&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
            <span class="s2">&quot;push_endpoint_topic&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
            <span class="s2">&quot;stored_secret&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
            <span class="s2">&quot;persistent&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span>
        <span class="p">},</span>
        <span class="s2">&quot;arn&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span>
        <span class="s2">&quot;opaqueData&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span>
    <span class="p">},</span>
    <span class="s2">&quot;subs&quot;</span><span class="p">:[]</span>
<span class="p">}</span>
</pre></div>
</div>
<ul class="simple">
<li><p>topic.user: name of the user that created the topic</p></li>
<li><p>name: name of the topic</p></li>
<li><p>dest.bucket_name: not used</p></li>
<li><p>dest.oid_prefix: not used</p></li>
<li><p>dest.push_endpoint: in case of S3-compliant notifications, this value will be used as the push-endpoint URL</p></li>
<li><p>if push-endpoint URL contain user/password information, request must be made over HTTPS. Topic get request will be rejected if not</p></li>
<li><p>dest.push_endpoint_args: in case of S3-compliant notifications, this value will be used as the push-endpoint args</p></li>
<li><p>dest.push_endpoint_topic: in case of S3-compliant notifications, this value will hold the topic name as sent to the endpoint (may be different than the internal topic name)</p></li>
<li><p>topic.arn: topic ARN</p></li>
<li><p>subs: list of subscriptions associated with this topic</p></li>
</ul>
</div>
<div class="section" id="delete-topic">
<h4><a class="toc-backref" href="#id11">Delete Topic</a><a class="headerlink" href="#delete-topic" title="Permalink to this headline">¶</a></h4>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">DELETE</span> <span class="o">/</span><span class="n">topics</span><span class="o">/&lt;</span><span class="n">topic</span><span class="o">-</span><span class="n">name</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>Delete the specified topic.</p>
</div>
<div class="section" id="list-topics">
<h4><a class="toc-backref" href="#id12">List Topics</a><a class="headerlink" href="#list-topics" title="Permalink to this headline">¶</a></h4>
<p>List all topics associated with a tenant.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">GET</span> <span class="o">/</span><span class="n">topics</span>
</pre></div>
</div>
<ul class="simple">
<li><p>if push-endpoint URL contain user/password information, in any of the topic, request must be made over HTTPS. Topic list request will be rejected if not</p></li>
</ul>
</div>
</div>
<div class="section" id="s3-compliant-notifications">
<h3><a class="toc-backref" href="#id13">S3-Compliant Notifications</a><a class="headerlink" href="#s3-compliant-notifications" title="Permalink to this headline">¶</a></h3>
<p>Detailed under: <a class="reference external" href="../s3/bucketops">Bucket Operations</a>.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<ul class="simple">
<li><p>Notification creation will also create a subscription for pushing/pulling events</p></li>
<li><p>The generated subscription’s name will have the same as the notification Id, and could be used later to fetch and ack events with the subscription API.</p></li>
<li><p>Notification deletion will deletes all generated subscriptions</p></li>
<li><p>In case that bucket deletion implicitly deletes the notification,
the associated subscription will not be deleted automatically (any events of the deleted bucket could still be access),
and will have to be deleted explicitly with the subscription deletion API</p></li>
<li><p>Filtering based on metadata (which is an extension to S3) is not supported, and such rules will be ignored</p></li>
<li><p>Filtering based on tags (which is an extension to S3) is not supported, and such rules will be ignored</p></li>
</ul>
</div>
</div>
<div class="section" id="non-s3-compliant-notifications">
<h3><a class="toc-backref" href="#id14">Non S3-Compliant Notifications</a><a class="headerlink" href="#non-s3-compliant-notifications" title="Permalink to this headline">¶</a></h3>
<div class="section" id="create-a-notification">
<h4><a class="toc-backref" href="#id15">Create a Notification</a><a class="headerlink" href="#create-a-notification" title="Permalink to this headline">¶</a></h4>
<p>This will create a publisher for a specific bucket into a topic.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>PUT /notifications/bucket/&lt;bucket&gt;?topic=&lt;topic-name&gt;[&amp;events=&lt;event&gt;[,&lt;event&gt;]]
</pre></div>
</div>
<p>Request parameters:</p>
<ul class="simple">
<li><p>topic-name: name of topic</p></li>
<li><p>event: event type (string), one of: <code class="docutils literal notranslate"><span class="pre">OBJECT_CREATE</span></code>, <code class="docutils literal notranslate"><span class="pre">OBJECT_DELETE</span></code>, <code class="docutils literal notranslate"><span class="pre">DELETE_MARKER_CREATE</span></code></p></li>
</ul>
</div>
<div class="section" id="delete-notification-information">
<h4><a class="toc-backref" href="#id16">Delete Notification Information</a><a class="headerlink" href="#delete-notification-information" title="Permalink to this headline">¶</a></h4>
<p>Delete publisher from a specific bucket into a specific topic.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>DELETE /notifications/bucket/&lt;bucket&gt;?topic=&lt;topic-name&gt;
</pre></div>
</div>
<p>Request parameters:</p>
<ul class="simple">
<li><p>topic-name: name of topic</p></li>
</ul>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>When the bucket is deleted, any notification defined on it is also deleted</p>
</div>
</div>
<div class="section" id="list-notifications">
<h4><a class="toc-backref" href="#id17">List Notifications</a><a class="headerlink" href="#list-notifications" title="Permalink to this headline">¶</a></h4>
<p>List all topics with associated events defined on a bucket.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">GET</span> <span class="o">/</span><span class="n">notifications</span><span class="o">/</span><span class="n">bucket</span><span class="o">/&lt;</span><span class="n">bucket</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>Response will have the following format (JSON):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="s2">&quot;topics&quot;</span><span class="p">:[</span>
   <span class="p">{</span>
      <span class="s2">&quot;topic&quot;</span><span class="p">:{</span>
         <span class="s2">&quot;user&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
         <span class="s2">&quot;name&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
         <span class="s2">&quot;dest&quot;</span><span class="p">:{</span>
            <span class="s2">&quot;bucket_name&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
            <span class="s2">&quot;oid_prefix&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
            <span class="s2">&quot;push_endpoint&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
            <span class="s2">&quot;push_endpoint_args&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
            <span class="s2">&quot;push_endpoint_topic&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span>
         <span class="p">}</span>
         <span class="s2">&quot;arn&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span>
      <span class="p">},</span>
      <span class="s2">&quot;events&quot;</span><span class="p">:[]</span>
   <span class="p">}</span>
 <span class="p">]}</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="subscriptions">
<h3><a class="toc-backref" href="#id18">Subscriptions</a><a class="headerlink" href="#subscriptions" title="Permalink to this headline">¶</a></h3>
<div class="section" id="create-a-subscription">
<h4><a class="toc-backref" href="#id19">Create a Subscription</a><a class="headerlink" href="#create-a-subscription" title="Permalink to this headline">¶</a></h4>
<p>Creates a new subscription.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>PUT /subscriptions/&lt;sub-name&gt;?topic=&lt;topic-name&gt;[?push-endpoint=&lt;endpoint&gt;[&amp;amqp-exchange=&lt;exchange&gt;][&amp;amqp-ack-level=none|broker|routable][&amp;verify-ssl=true|false][&amp;kafka-ack-level=none|broker][&amp;ca-location=&lt;file path&gt;]]
</pre></div>
</div>
<p>Request parameters:</p>
<ul class="simple">
<li><p>topic-name: name of topic</p></li>
<li><p>push-endpoint: URI of endpoint to send push notification to</p></li>
</ul>
<p>The endpoint URI may include parameters depending with the type of endpoint:</p>
<ul class="simple">
<li><p>HTTP endpoint</p></li>
</ul>
<blockquote>
<div><ul class="simple">
<li><p>URI: <code class="docutils literal notranslate"><span class="pre">http[s]://&lt;fqdn&gt;[:&lt;port]</span></code></p></li>
<li><p>port defaults to: 80/443 for HTTP/S accordingly</p></li>
<li><p>verify-ssl: indicate whether the server certificate is validated by the client or not (“true” by default)</p></li>
</ul>
</div></blockquote>
<ul class="simple">
<li><p>AMQP0.9.1 endpoint</p></li>
</ul>
<blockquote>
<div><ul class="simple">
<li><p>URI: <code class="docutils literal notranslate"><span class="pre">amqp://[&lt;user&gt;:&lt;password&gt;&#64;]&lt;fqdn&gt;[:&lt;port&gt;][/&lt;vhost&gt;]</span></code></p></li>
<li><p>user/password defaults to : guest/guest</p></li>
<li><p>port defaults to: 5672</p></li>
<li><p>vhost defaults to: “/”</p></li>
<li><p>amqp-exchange: the exchanges must exist and be able to route messages based on topics (mandatory parameter for AMQP0.9.1)</p></li>
<li><p>amqp-ack-level: no end2end acking is required, as messages may persist in the broker before delivered into their final destination. Three ack methods exist:</p></li>
</ul>
<blockquote>
<div><ul class="simple">
<li><p>“none”: message is considered “delivered” if sent to broker</p></li>
<li><p>“broker”: message is considered “delivered” if acked by broker (default)</p></li>
<li><p>“routable”: message is considered “delivered” if broker can route to a consumer</p></li>
</ul>
</div></blockquote>
</div></blockquote>
<ul class="simple">
<li><p>Kafka endpoint</p></li>
</ul>
<blockquote>
<div><ul class="simple">
<li><p>URI: <code class="docutils literal notranslate"><span class="pre">kafka://[&lt;user&gt;:&lt;password&gt;&#64;]&lt;fqdn&gt;[:&lt;port]</span></code></p></li>
<li><p>if <code class="docutils literal notranslate"><span class="pre">ca-location</span></code> is provided, secure connection will be used for connection with the broker</p></li>
<li><p>user/password may only be provided over HTTPS. Topic creation request will be rejected if not</p></li>
<li><p>user/password may only be provided together with <code class="docutils literal notranslate"><span class="pre">ca-location</span></code>. Topic creation request will be rejected if not</p></li>
<li><p>port defaults to: 9092</p></li>
<li><p>kafka-ack-level: no end2end acking is required, as messages may persist in the broker before delivered into their final destination. Two ack methods exist:</p></li>
</ul>
<blockquote>
<div><ul class="simple">
<li><p>“none”: message is considered “delivered” if sent to broker</p></li>
<li><p>“broker”: message is considered “delivered” if acked by broker (default)</p></li>
</ul>
</div></blockquote>
</div></blockquote>
</div>
<div class="section" id="get-subscription-information">
<h4><a class="toc-backref" href="#id20">Get Subscription Information</a><a class="headerlink" href="#get-subscription-information" title="Permalink to this headline">¶</a></h4>
<p>Returns information about specific subscription.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">GET</span> <span class="o">/</span><span class="n">subscriptions</span><span class="o">/&lt;</span><span class="n">sub</span><span class="o">-</span><span class="n">name</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>Response will have the following format (JSON):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
    <span class="s2">&quot;user&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
    <span class="s2">&quot;name&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
    <span class="s2">&quot;topic&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
    <span class="s2">&quot;dest&quot;</span><span class="p">:{</span>
        <span class="s2">&quot;bucket_name&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
        <span class="s2">&quot;oid_prefix&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
        <span class="s2">&quot;push_endpoint&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
        <span class="s2">&quot;push_endpoint_args&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
        <span class="s2">&quot;push_endpoint_topic&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span>
    <span class="p">}</span>
    <span class="s2">&quot;s3_id&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span>
<span class="p">}</span>
</pre></div>
</div>
<ul class="simple">
<li><p>user: name of the user that created the subscription</p></li>
<li><p>name: name of the subscription</p></li>
<li><p>topic: name of the topic the subscription is associated with</p></li>
<li><p>dest.bucket_name: name of the bucket storing the events</p></li>
<li><p>dest.oid_prefix: oid prefix for the events stored in the bucket</p></li>
<li><p>dest.push_endpoint: in case of S3-compliant notifications, this value will be used as the push-endpoint URL</p></li>
<li><p>if push-endpoint URL contain user/password information, request must be made over HTTPS. Topic get request will be rejected if not</p></li>
<li><p>dest.push_endpoint_args: in case of S3-compliant notifications, this value will be used as the push-endpoint args</p></li>
<li><p>dest.push_endpoint_topic: in case of S3-compliant notifications, this value will hold the topic name as sent to the endpoint (may be different than the internal topic name)</p></li>
<li><p>s3_id: in case of S3-compliant notifications, this will hold the notification name that created the subscription</p></li>
</ul>
</div>
<div class="section" id="delete-subscription">
<h4><a class="toc-backref" href="#id21">Delete Subscription</a><a class="headerlink" href="#delete-subscription" title="Permalink to this headline">¶</a></h4>
<p>Removes a subscription.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">DELETE</span> <span class="o">/</span><span class="n">subscriptions</span><span class="o">/&lt;</span><span class="n">sub</span><span class="o">-</span><span class="n">name</span><span class="o">&gt;</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="events">
<h3><a class="toc-backref" href="#id22">Events</a><a class="headerlink" href="#events" title="Permalink to this headline">¶</a></h3>
<div class="section" id="pull-events">
<h4><a class="toc-backref" href="#id23">Pull Events</a><a class="headerlink" href="#pull-events" title="Permalink to this headline">¶</a></h4>
<p>Pull events sent to a specific subscription.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>GET /subscriptions/&lt;sub-name&gt;?events[&amp;max-entries=&lt;max-entries&gt;][&amp;marker=&lt;marker&gt;]
</pre></div>
</div>
<p>Request parameters:</p>
<ul class="simple">
<li><p>marker: pagination marker for list of events, if not specified will start from the oldest</p></li>
<li><p>max-entries: max number of events to return</p></li>
</ul>
<p>The response will hold information on the current marker and whether there are more events not fetched:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="s2">&quot;next_marker&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span><span class="s2">&quot;is_truncated&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span><span class="o">...</span><span class="p">}</span>
</pre></div>
</div>
<p>The actual content of the response is depended with how the subscription was created.
In case that the subscription was created via an S3-compatible notification,
the events will have an S3-compatible record format (JSON):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="s2">&quot;Records&quot;</span><span class="p">:[</span>
    <span class="p">{</span>
        <span class="s2">&quot;eventVersion&quot;</span><span class="p">:</span><span class="s2">&quot;2.1&quot;</span>
        <span class="s2">&quot;eventSource&quot;</span><span class="p">:</span><span class="s2">&quot;aws:s3&quot;</span><span class="p">,</span>
        <span class="s2">&quot;awsRegion&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
        <span class="s2">&quot;eventTime&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
        <span class="s2">&quot;eventName&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
        <span class="s2">&quot;userIdentity&quot;</span><span class="p">:{</span>
            <span class="s2">&quot;principalId&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span>
        <span class="p">},</span>
        <span class="s2">&quot;requestParameters&quot;</span><span class="p">:{</span>
            <span class="s2">&quot;sourceIPAddress&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span>
        <span class="p">},</span>
        <span class="s2">&quot;responseElements&quot;</span><span class="p">:{</span>
            <span class="s2">&quot;x-amz-request-id&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
            <span class="s2">&quot;x-amz-id-2&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span>
        <span class="p">},</span>
        <span class="s2">&quot;s3&quot;</span><span class="p">:{</span>
            <span class="s2">&quot;s3SchemaVersion&quot;</span><span class="p">:</span><span class="s2">&quot;1.0&quot;</span><span class="p">,</span>
            <span class="s2">&quot;configurationId&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
            <span class="s2">&quot;bucket&quot;</span><span class="p">:{</span>
                <span class="s2">&quot;name&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
                <span class="s2">&quot;ownerIdentity&quot;</span><span class="p">:{</span>
                    <span class="s2">&quot;principalId&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span>
                <span class="p">},</span>
                <span class="s2">&quot;arn&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
                <span class="s2">&quot;id&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span>
            <span class="p">},</span>
            <span class="s2">&quot;object&quot;</span><span class="p">:{</span>
                <span class="s2">&quot;key&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
                <span class="s2">&quot;size&quot;</span><span class="p">:</span><span class="s2">&quot;0&quot;</span><span class="p">,</span>
                <span class="s2">&quot;eTag&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
                <span class="s2">&quot;versionId&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
                <span class="s2">&quot;sequencer&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
                <span class="s2">&quot;metadata&quot;</span><span class="p">:[],</span>
                <span class="s2">&quot;tags&quot;</span><span class="p">:[]</span>
            <span class="p">}</span>
        <span class="p">},</span>
        <span class="s2">&quot;eventId&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
        <span class="s2">&quot;opaqueData&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
    <span class="p">}</span>
<span class="p">]}</span>
</pre></div>
</div>
<ul class="simple">
<li><p>awsRegion: zonegroup</p></li>
<li><p>eventTime: timestamp indicating when the event was triggered</p></li>
<li><p>eventName: either <code class="docutils literal notranslate"><span class="pre">s3:ObjectCreated:</span></code>, or <code class="docutils literal notranslate"><span class="pre">s3:ObjectRemoved:</span></code></p></li>
<li><p>userIdentity: not supported</p></li>
<li><p>requestParameters: not supported</p></li>
<li><p>responseElements: not supported</p></li>
<li><p>s3.configurationId: notification ID that created the subscription for the event</p></li>
<li><p>s3.bucket.name: name of the bucket</p></li>
<li><p>s3.bucket.ownerIdentity.principalId: owner of the bucket</p></li>
<li><p>s3.bucket.arn: ARN of the bucket</p></li>
<li><p>s3.bucket.id: Id of the bucket (an extension to the S3 notification API)</p></li>
<li><p>s3.object.key: object key</p></li>
<li><p>s3.object.size: not supported</p></li>
<li><p>s3.object.eTag: object etag</p></li>
<li><p>s3.object.version: object version in case of versioned bucket</p></li>
<li><p>s3.object.sequencer: monotonically increasing identifier of the change per object (hexadecimal format)</p></li>
<li><p>s3.object.metadata: not supported (an extension to the S3 notification API)</p></li>
<li><p>s3.object.tags: not supported (an extension to the S3 notification API)</p></li>
<li><p>s3.eventId: unique ID of the event, that could be used for acking (an extension to the S3 notification API)</p></li>
<li><p>s3.opaqueData: opaque data is set in the topic configuration and added to all notifications triggered by the topic (an extension to the S3 notification API)</p></li>
</ul>
<p>In case that the subscription was not created via a non S3-compatible notification,
the events will have the following event format (JSON):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="p">{</span><span class="s2">&quot;events&quot;</span><span class="p">:[</span>
    <span class="p">{</span>
        <span class="s2">&quot;id&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
        <span class="s2">&quot;event&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
        <span class="s2">&quot;timestamp&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
        <span class="s2">&quot;info&quot;</span><span class="p">:{</span>
            <span class="s2">&quot;attrs&quot;</span><span class="p">:{</span>
                <span class="s2">&quot;mtime&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span>
            <span class="p">},</span>
            <span class="s2">&quot;bucket&quot;</span><span class="p">:{</span>
                <span class="s2">&quot;bucket_id&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
                <span class="s2">&quot;name&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
                <span class="s2">&quot;tenant&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span>
            <span class="p">},</span>
            <span class="s2">&quot;key&quot;</span><span class="p">:{</span>
                <span class="s2">&quot;instance&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span><span class="p">,</span>
                <span class="s2">&quot;name&quot;</span><span class="p">:</span><span class="s2">&quot;&quot;</span>
            <span class="p">}</span>
        <span class="p">}</span>
    <span class="p">}</span>
<span class="p">]}</span>
</pre></div>
</div>
<ul class="simple">
<li><p>id: unique ID of the event, that could be used for acking</p></li>
<li><p>event: one of: <code class="docutils literal notranslate"><span class="pre">OBJECT_CREATE</span></code>, <code class="docutils literal notranslate"><span class="pre">OBJECT_DELETE</span></code>, <code class="docutils literal notranslate"><span class="pre">DELETE_MARKER_CREATE</span></code></p></li>
<li><p>timestamp: timestamp indicating when the event was sent</p></li>
<li><p>info.attrs.mtime: timestamp indicating when the event was triggered</p></li>
<li><p>info.bucket.bucket_id: id of the bucket</p></li>
<li><p>info.bucket.name: name of the bucket</p></li>
<li><p>info.bucket.tenant: tenant the bucket belongs to</p></li>
<li><p>info.key.instance: object version in case of versioned bucket</p></li>
<li><p>info.key.name: object key</p></li>
</ul>
</div>
<div class="section" id="ack-event">
<h4><a class="toc-backref" href="#id24">Ack Event</a><a class="headerlink" href="#ack-event" title="Permalink to this headline">¶</a></h4>
<p>Ack event so that it can be removed from the subscription history.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>POST /subscriptions/&lt;sub-name&gt;?ack&amp;event-id=&lt;event-id&gt;
</pre></div>
</div>
<p>Request parameters:</p>
<ul class="simple">
<li><p>event-id: id of event to be acked</p></li>
</ul>
</div>
</div>
</div>
</div>



           </div>
           
          </div>
          <footer>
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
        <a href="../s3-notification-compatibility/" class="btn btn-neutral float-right" title="S3 桶通知的兼容性" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
        <a href="../cloud-sync-module/" class="btn btn-neutral float-left" title="云同步模块" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>
        &#169; Copyright 2016, Ceph authors and contributors. Licensed under Creative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0).

    </p>
  </div> 

</footer>
        </div>
      </div>

    </section>

  </div>
  

  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script>

  
  
    
   

</body>
</html>